/**
 * 认证响应DTO
 * 
 * 功能说明：
 * - 封装用户登录/注册成功后的响应数据
 * - 包含访问令牌、刷新令牌和用户基本信息
 * - 提供用户权限信息，支持前端权限控制
 * - 支持JWT令牌的后续使用和用户信息展示
 * 
 * 数据结构：
 * - 令牌信息：token（访问令牌）、refreshToken（刷新令牌）
 * - 用户基本信息：userId、username、email、phoneNumber等
 * - 用户权限信息：roles（角色列表）、userType（用户类型）
 * - 时间信息：lastLoginTime（最后登录时间）
 * 
 * 使用场景：
 * - 用户登录成功后，返回给前端的响应数据
 * - 用户注册成功后，返回给前端的响应数据
 * - 令牌刷新成功后，返回新的认证信息
 * - 前端存储令牌信息，用于后续API调用
 * 
 * 安全考虑：
 * - 令牌信息需要安全存储，建议使用httpOnly cookie或安全存储
 * - 不包含敏感信息如密码等
 * - 权限信息用于前端路由和按钮级别的权限控制
 * 
 * 性能优化：
 * - 使用@Data注解自动生成getter/setter方法
 * - 提供全参构造函数，方便对象创建
 * - 提供无参构造函数，支持JSON反序列化
 * 
 * @author eCommerce Team
 * @version 1.0
 */
package com.ecommerce.auth.dto;

import lombok.Data;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 认证响应DTO
 * 封装用户认证成功后的响应数据，包含令牌和用户信息
 */
@Data
public class AuthResponse {

    /**
     * 访问令牌（JWT）
     * - 用于访问受保护的API接口
     * - 通常有效期较短（如24小时）
     * - 需要包含在HTTP请求的Authorization头中
     */
    private String token;

    /**
     * 刷新令牌
     * - 用于获取新的访问令牌
     * - 通常有效期较长（如7天）
     * - 当访问令牌过期时使用刷新令牌获取新令牌
     */
    private String refreshToken;

    /**
     * 用户ID
     * - 用户的唯一标识符
     * - 用于后续API调用中标识用户身份
     * - 数据库主键，全局唯一
     */
    private Long userId;

    /**
     * 用户名
     * - 用户登录时使用的用户名
     * - 用于用户界面展示
     * - 在整个系统中唯一
     */
    private String username;

    /**
     * 邮箱地址
     * - 用户的邮箱地址
     * - 用于找回密码、接收通知等
     * - 在整个系统中唯一
     */
    private String email;

    /**
     * 手机号码
     * - 用户的手机号码
     * - 用于接收短信验证码、找回密码等
     * - 可选字段，可能为null
     */
    private String phoneNumber;

    /**
     * 用户昵称
     * - 用户的显示名称
     * - 用于用户界面展示，比用户名更友好
     * - 可选字段，可能为null
     */
    private String nickName;

    /**
     * 用户地址
     * - 用户的收货地址信息
     * - 用于订单配送等场景
     * - 可选字段，可能为null
     */
    private String address;

    /**
     * 头像URL
     * - 用户头像图片的存储地址
     * - 用于用户界面展示用户头像
     * - 可选字段，可能为null
     */
    private String avatarUrl;

    /**
     * 用户性别
     * - 用户的性别信息
     * - 枚举值：MALE（男）、FEMALE（女）、UNKNOWN（未知）
     * - 用于用户个人信息展示
     */
    private String gender;

    /**
     * 最后登录时间
     * - 用户最后一次成功登录的时间
     * - 用于安全分析和用户活跃度统计
     * - 格式：ISO 8601标准时间格式
     */
    private LocalDateTime lastLoginTime;

    /**
     * 用户角色列表
     * - 用户拥有的所有角色名称
     * - 用于前端权限控制和路由判断
     * - 例如：["USER", "ADMIN"]
     */
    private List<String> roles;

    /**
     * 用户类型
     * - 用户的类型信息
     * - 枚举值：CUSTOMER（普通用户）、ADMIN（管理员）、MERCHANT（商家）
     * - 用于区分不同用户群体的权限和功能
     */
    private String userType;

    /**
     * 无参构造函数
     * - 用于JSON反序列化
     * - Spring框架需要无参构造函数进行对象创建
     */
    public AuthResponse() {
    }

    /**
     * 全参构造函数
     * - 用于手动创建响应对象
     * - 包含所有字段的初始化
     * - 方便在业务逻辑中创建完整的响应对象
     * 
     * @param token 访问令牌
     * @param refreshToken 刷新令牌
     * @param userId 用户ID
     * @param username 用户名
     * @param email 邮箱地址
     * @param phoneNumber 手机号码
     * @param nickName 用户昵称
     * @param address 用户地址
     * @param avatarUrl 头像URL
     * @param gender 用户性别
     * @param lastLoginTime 最后登录时间
     * @param roles 用户角色列表
     * @param userType 用户类型
     */
    public AuthResponse(String token, String refreshToken, Long userId, String username, String email, 
                       String phoneNumber, String nickName, String address, String avatarUrl, String gender, 
                       LocalDateTime lastLoginTime, List<String> roles, String userType) {
        this.token = token;
        this.refreshToken = refreshToken;
        this.userId = userId;
        this.username = username;
        this.email = email;
        this.phoneNumber = phoneNumber;
        this.nickName = nickName;
        this.address = address;
        this.avatarUrl = avatarUrl;
        this.gender = gender;
        this.lastLoginTime = lastLoginTime;
        this.roles = roles;
        this.userType = userType;
    }
}